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GF Subsystem Overview 
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Purpose 
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¢ Much SPICE software computes a geometry 
parameter at a given time, t, i.e. x = f(t). 
— Example: on 2011 MAR 30 14:57:08, what is the spacecraft’s altitude 
above Mars? 


¢ The Geometry Finder subsystem does the inverse: it 
finds times when specified geometric events occur. 


— Example: within some time bounds, when is the spacecraft’s 
altitude between 50 and 100 km? 
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Some Examples 
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¢ The SPICE Geometry Finder (GF) subsystem finds 
times when specified geometric events occur. 


— A “geometric event” is an occurrence of a given geometric quantity 
satisfying a specified condition. For example: 


» Mars Express distance from Mars is at a local minimum 
(periapse) 


» Elevation of the Cassini orbiter is above a given threshold angle 
as seen from DSS-14 


» Titan is completely occulted by Saturn 


» The Saturn phase angle as seen by the Cassini orbiter is 60 
degrees 


— Each GF search is conducted over a user-specified time window, 
called the confinement window. 


» A “time window” is a union of time intervals. 


— The result of a GF search is the time window over which the 
specified condition is met. 
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Types of GF APIs 
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¢ GF provides two primary types of event-finding APIs 
— Boolean: a geometric condition (an event) is true or false 
» Example: Phobos is occulted by Mars 
» Example: Vesta is not in the OSIRIS instrument’s field of view 
— We also call these binary conditions 


— Numeric: a geometric quantity has a given value, is within a given 
range or has achieved a local or global maximum or minimum 


» Example: spacecraft altitude is between X and Y km above the 
surface 


» Example: angular separation of Titan from Saturn has reached 
the maximum value 
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GF High-Level API Routines 
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¢ The GF subsystem provides the following high-level API 
routines; these search for events involving the respective 
geometric quantities listed below 


GFDIST: observer-target distance 

GFILUM: illumination angles 

GFOCLT: occultations or transits 

GFPA: phase angle 

GFPOSC: position vector coordinates 

GFRFOV: ray is contained in an instrument’s field of view 
GFRR: observer-target range rate 

GFSEP: target body angular separation 

GFSNTC: ray-body surface intercept coordinates 

GFSUBC: sub-observer point coordinates 

GFTFOV: target body appears in an instrument’s field of view 
GFUDB: user-defined Boolean quantity (only Fortran, C and JNI) 
GFUDS: user-defined scalar quantity (only Fortran, C and JNI) 


Geometry Finder Subsystem 


NAIE> The SPICE Window 
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¢ The high-level GF routines return a search result as a 
SPICE window. This window specifies intervals of time 
when the user’s constraints are satisfied. 


¢ In simple terms, one can describe a SPICE window as: 


— A span of time defined by a start time and an end time, 
containing a list of disjoint intervals arranged in ascending 
order. 


— Within that time span, a time-ordered sequence of zero or more 
time intervals each having Zero or non-zero length 
» An interval is specified by a pair of double precision 
numbers, with the second greater than or equal to the first. 


» A zero-length interval is often called a “singleton” 


interval | [Interval2] [| _Intervaln 


T T 
ar A SPICE Window ep 
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¢ SPICE provides routines to: 


— compute unions, intersections, and differences 
of windows 


— contract each interval within a window ... 


» by increasing the left endpoint and 
decreasing the right endpoint 


¢ These functions allow one to search for 
multi-condition events 


¢ See the next page for an example 


Geometry Finder Subsystem 


Example of Window Operations 
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Given an initial confinement window, A, determine times when CK and SPK data 
are available within it. 


Use CKCOV and SPKCOV to find CK and SPK availability windows, B and C. Use 
window intersection to obtain the results window. 


Contract the CK window slightly to avoid round-off problems. Contract the SPK window by a 
few seconds if discrete differentiation is used by search algorithms (e.g. for acceleration or 
for “is function decreasing?” tests). 


Original confinement window “A” 


Reconstructed pointing availability window “B” 
Spacecraft ephemeris availability window “C” 


Data availability window “A1” = B intersect C 


 _—_§_ i ——3t———{iadt_iiyt+tMH_Aagx 
Results window “A2” =A intersect A1 
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Using Time Windows in GF 
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¢ GF uses a SPICE window to: 


— confine the time bounds over which your search is to take 
place 


Search Confinement Window 


@ 
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Using Time Windows in GF 
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¢ GF uses SPICE windows for input and output 


— Input: confine the time bounds over which your search is to 
take place 


— Output: contain the time intervals that meet the search criteria 
» There may be none, one or multiple result intervals 


» The result intervals can be of non-zero or zero length 
¢ A zero-length interval is simply an epoch—an instant in time 


Intervals contained in output window 


— [ee 


Non-zero length Zero length 


result intervals result intervals 
(singletons) 
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Using Multiple SPICE Windows 
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¢ The result window (the output) from one search 
can be used as the confinement window (the 
input) for a subsequent search. 


— This is often a convenient and efficient way of performing 
searches for times when multiple constraints are met. 


— This technique can be used to accelerate searches in cases 
where an initial, fast search can be performed to produce a 
small confinement window for a second, slower search. 


» See the next chart and the example program “CASCADE” 
in the Geometry Finder Required Reading document 
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Cascading Search Example 
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Example: accelerate a solar occultation search. 


First search for times when the angular separation of the Sun and Moon, as seen 
from an earth station, is less than 3 degrees. 


Use the result window of the angular separation search as the confinement 
window of an occultation search. 


Because the angular separation search is much faster than would be the 
occultation search on the original confinement window, the total search time is 
greatly reduced. 


Original confinement window (“A”) 


eo 


Result of angular separation search: second confinement window (“B”) 


4} + 


Window “C”: result of occultation search performed on window “B” 
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¢ The GF module headers contain complete 
example programs for each GF API routine 


¢ The GF Required Reading document (gf.req) 
contains lots of details 


¢ Documentation on SPICE windows: 


— The WINDOWS Required Reading windows.req 
— The Other Functions tutorial 
— API documentation for SPICE window routines 
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GF Search Examples 


NAIF »pistance is Local Maximum (or Minimum) 
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Mars-MEX position 
vector 


API: GFDIST 
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HAIES 


Distance Within a Range 
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Geometry Finder Subsystem 


API: GFDIST 


Range Rate Extremum 
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Lunar 


Station 


Moon 


API: GFRR 


NAIE> Angular Separation Inequality Search -1 
Navigation and Ancillary Information Facility 


Rover location 


ular separation of position vectors 


< MRO 


LM LL API: GFSEP 


Geometry Finder Subsystem 20 


HAIES 


Angular Separation Inequality Search -2 
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Geometry Finder Subsystem 


Angular separation of Earth 
figures 


API: GFSEP 
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Occultation/Transit Search 
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Point target 
Phobos in in occultation Phobos in 
annular partial transit 


transit 


Point target 


in transit 
Earth 
hobos in full 
Phobos in occultation 
partial 
occultation API: GFOCLT 
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Target in Field of View 
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Titan 


Cassini Camera FOV 


Cassini 


< orbiter 
MP} MM 


API: GFTFOV 
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NAIE> Ray in FOV Search 
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Cassini ISS NAC FOV 


Cassini 


< orbiter 
uP} LU 


API: GFRFOV 
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Position Coordinate Local Extremum Search 


Navigation and Ancillary Information Facility 


J2000 Z 
Earth-Sun direction 


Point of 
max latitude 


Unit sphere 


Planetocentric 

Latitude 
Path of sub-solar point 
on unit sphere (in red) 


J2000 X 
J2000 Y 


API: GFPOSC 
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NAIE> Position Coordinate Equality Search 
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J2000 Z 


Path of sub-solar point 


on unit sphere (in red) J2000 Y 


Earth-Sun direction at epoch 
of J2000 equator crossing 
J2000 X 


API: GFPOSC 
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NAIE> Position Coordinate Inequality Search -1 
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DSS-13 TOPO Z 


DSS-13_ TOPO X 


Direction to MRO | 
Wii, 


6 deg. elevation 


DSS-13_ 


API: GFPOSC 
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NAIE> Position Coordinate Inequality Search -2 
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LRO s/c frame +X axis 


LRO s/c frame +Y axis 


Colatitude of LRO-Moon position 
vector in LRO s/c frame 


LRO s/c frame +Z axis 


API: GFPOSC 
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Sub-Observer Point Coordinate Equality Search 
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Body-fixed Z 


Outward surface MP} 
Path of sub-spacecraft normal direction at 
7 sub-spacecraft point epererrae 


point (in red) 


Planetocentric 
latitude = 25 deg. 


Body-fixed Y 


Body-fixed X 
API: GFSUBC 
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Surface Intercept Coordinate Equality Search 
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Body-fixed Z 


an aa 


Spacecraft 


Path of boresight 
intercept (in red) 


Camera boresight 
direction at epoch of 
meridian crossing 


Body-fixed Y 


Planetographic 
Body-fixed X longitude = 45 deg. 


API: GFSNTC 
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Surface Intercept “Box” Search 
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Body-fixed Z 


ao aa 


Path of boresight Speen 


Planetographic Latitude intercept (in red) Camera boresight 


0 to 30 deg. direction 
Body-fixed Y 
Planetographic Longitude 
Body-fixed X -45 to -70 deg. 
API: GFSNTC 
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Surface Intercept Coordinate Equality Search 
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Find the time at which the ring plane intercept of the Cassini to DSS-13 
vector, corrected for transmission light time (stellar aberration 
correction is unnecessary), has radius 300000km. 

The solution requires a dynamic frame for which one axis points along 
the radiation path. 


IAU_SATURN Z 4 Cassini orbiter 
IAU_SATURNX __ LUM 


Cassini to DSS-13 
radiation direction 


[ “Ring plane” ellipsoid: 1¢m 
o_ 2 thick, radius 600000 km, 
7 Path of radiation centered at Saturn’s center 


Earth ~~ intercept (in red) 
A” 


pees API: GFSNTC 
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User-Defined Quantity Extremum Search 
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Apparent position of 
Titan, computed using 
LT+S correction 


Geometric 
position of Angular separation of 


Titan position vectors 


4 Cassini orbiter 


LMU 


API: GFUDS 
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Geometric Search Types and Constraints 


Geometry Finder Subsystem 
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NAIE> Types of Geometric Quantities 


¢ The GF subsystem deals with two types of 
geometric quantities: 


— “Binary state functions”: functions of time that can 
be “true” or “false.” Examples: 


» Occultation state, such as: “Titan is fully occulted by 
Saturn at time t” 


» Visibility state: A target body or object modeled as a ray 
(for example, a star) is visible in a specified instrument 
FOV at time t 
— Scalar numeric functions of time, for example 
» Observer-target distance 


» Latitude or longitude of an observer-target vector, sub- 
spacecraft point, or ray-surface intercept point 

» Angular separation of two target bodies as seen by an 
observer 
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NAIE> Binary State Searches 
Navigation and Ancillary Information Facility 


¢ Binary state searches find times when a 
specified binary state function takes the value 
“true.” 


— SPICE window arithmetic can be used to find the times when 
a binary state function is “false.” 
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Numeric Searches 
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¢ Numeric searches find times when a scalar numeric 
quantity satisfies a mathematical constraint. The 
supported constraints are: 

— The function 

equals a specified reference value. 

is less than a specified reference value. 

is greater than a specified reference value. 

is ata local maximum. 

is ata local minimum. 

is at an absolute maximum. 

is at an absolute minimum. 


is at an “adjusted” absolute maximum: the function is within a 
given tolerance of the absolute maximum. 


is at an “adjusted” absolute minimum: the function is within a 
given tolerance of the absolute minimum. 


¢ Examples for a Distance search follow. 


\ ~~ ~~~ 


Y 
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NAIE> Solve Distance Equality 
Navigation and Ancillary Information Facility 


Find times at which Distance = Dy 


GF API input arguments defining constraint: 


RELATE = ‘=’ 
ADJUST = 0.DO 
REFVAL = DO 


Distance 
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NAIE> Solve Distance < Inequality 
Navigation and Ancillary Information Facility 


Find times during which Distance < Dy 


GF API input arguments defining constraint: 


RELATE = ‘<’ 
ADJUST = 0.DO 
REFVAL = DO 


Distance 
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NAIE> Solve Distance > Inequality 
Navigation and Ancillary Information Facility 


Find times during which Distance > Dy 


GF API input arguments defining constraint: 


RELATE = ‘>‘ 
ADJUST = 0.DO 
REFVAL = DO 


Distance 


Time 
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Find Local Minima 


Navigation and Ancillary Information Facility 


Find times at which Distance is a local minimum. 


GF API input arguments defining constraint: 


RELATE 


ADJUST 
REFVAL 


‘LOCMIN’ 
0.DO 
0.DO 


Distance 
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(REFVAL is not used in this case 
but should be initialized for portability) 


Time 
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Find Local Maxima 
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Find times at which Distance is a local maximum. 


GF API input arguments defining constraint: 


RELATE = ‘LOCMAX’ 
0.DO (REFVAL is not used in this case 
but should be initialized for portability) 


ADJUST = 


REFVAL = 0.DO 


Not 
Solutions 


Local extrema are 
always in the 
interior of the 
confinement 
window, 

never on the 
boundary 


Distance 
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Dyin 


Distance 
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Find Absolute Minimum 


Navigation and Ancillary Information Facility 


Time 
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Find Absolute Maximum 


Navigation and Ancillary Information Facility 


Find the time at which Distance is an absolute maximum. 


GF API input arguments defining constraint: 


RELATE = ‘ABSMAX’ 
ADJUST = 0.DO (REFVAL is not used in this case 
but should be initialized for portability) 


REFVAL = 0.DO 


Distance 


Geometry Finder Subsystem 44 


Find Adjusted Absolute Minimum 


Navigation and Ancillary Information Facility 


Find times at which Distance < Dap, = Dyn + ADJo 


GF API input arguments defining constraint: 


RELATE = ‘ABSMIN’ 


ADJUST = ADJO (ADJO> 0) 
(REFVAL is not used in this case but should be initialized for portability) 


REFVAL = 0.DO 


Distance 


Time 
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Find Adjusted Absolute Maximum 


Navigation and Ancillary Information Facility 


Find times at which Distance > Dap = Dyyay - ADJo 


GF API input arguments defining constraint: 
RELATE = ‘ABSMAX’ 
ADJUST = ADJO (ADJO> 0) 


REFVAL = 0.DO (REFVAL is not used in this case but should be initialized for portability) 


Distance 


Time 
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More Details 


¢ GF mid-level APIs 


¢ Root Finding, including step 
size selection 


¢ Workspace 
¢ API Example: GFDIST 
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GF Mid-Level API Routines 
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¢ The Fortran and C SPICE Toolkits provide some mid- 
level APIs that provide additional capabilities: 
— Progress reporting, which can be customized by the user 
— Interrupt handling which can be customized by the user 
» In Fortran, no default interrupt detection is available 
— User-customizable search step and refinement routines 
— User-adjustable root finding convergence tolerance 


¢ The GF mid-level search APIs are: 
— GFEVNT: All scalar numeric quantity searches 
— GFFOVE: Target or ray in FOV searches 
— GFOCCE: Occultation searches 
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Geometry Finder Subsystem 
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Root Finding 
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Root Finding 
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¢ To produce a final or intermediate result window, the GF 
subsystem must accurately locate the endpoints of the window’s 
intervals. These endpoints are called “roots.” 


— The green regions below (rectangles and vertical line segment) represent 
intervals of a window. 


— Roots are indicated by the red, vertical arrows. 


eee Bel eee 


¢ Elsewhere, “root finding” often refers to solving f(x) = 0. 


¢ Inthe GF setting, roots are boundaries of time intervals over which 
a specified constraint is met. 
— Roots can be times when a binary state function changes values. 


¢ Most popular root finding methods, e.g. Newton, secant, bisection, 
require the user to first “bracket” a root: that is, determine two 
abscissa values such that a single root is located between those 
values. 

¢ The GF subsystem solves a more difficult problem: it performs a 
global search for roots. That is, given correct inputs, it finds all 
roots within a user-specified confinement window. 

— The user is not asked to bracket the roots. 
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¢ The GF subsystem asks the user to specify a time 
step (often called the‘step size”) that will be used 
to bracket roots. 

— For binary state searches, the step size is used to 
bracket the endpoints of the intervals of the result 
window. 

» The step size must be shorter than any event of 
interest, and shorter than any interval between 
events that are to be distinguished. 

— For numeric searches, the step size is used to bracket 
the endpoints of the intervals of the window on which 
the geometric quantity is monotonically decreasing. 

» The step size must be shorter than any interval on 
which the function is monotonically increasing or 
decreasing. 


— In both cases, the step size must be large enough so the 
search completes in a reasonable amount of time. 
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Monotone Windows -1 


Navigation and Ancillary Information Facility 


Example: monotone windows for a distance function 


Note that: 
Extrema occur only at window interval boundaries. 


Each window interval contains at most one root of an equality condition. 
Within each window interval, the solution of an inequality is a single (possibly empty) interval. 


Distance 


Time 
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Monotone Windows-2 


Navigation and Ancillary Information Facility 


The shortest interval on which the function is monotonically 
increasing or decreasing may be LONGER than the event of interest. 


For example, consider the search for times when D < Do. The result 
window consists of the interval [to, t;] shown below. 


Distance 
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Bracketing Interval Endpoints 
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¢ Inthe diagram below, the green boxes denote intervals of a 
window. 


¢ The start of the first interval is bracketed by the first and second 
times; the end of the first interval is bracketed by the third and 
fourth times. The start of the second interval is bracketed by the 
fourth and fifth times. 


step size 
“delta” 


ty ty ts ty ts ts ty 


step = 3*delta 


+. _ step = 2*delta 


¢ The step size is a critical determinant of the completeness 
of the solution: 


— If the step size were equal to 3*delta, the first interval would not be 
seen. 


— If the step size were equal to 2*delta, the first and second intervals 
would not be seen as distinct. 
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NAIE> Solving for Interval Endpoints 
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step size 
“delta” 


t, ty ts ty ts te t7 


¢ Once an interval endpoint is bracketed, the GF subsystem 
performs a refinement search to locate the endpoint 
precisely (shown by the red arrows). 
— The default tolerance for convergence is 1.e-6 second. 
¢ The refinement search is usually relatively fast compared to 
the interval bracketing search. 
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The Result Window 
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¢ For binary state searches, the window whose endpoints are 
found IS the result window. 


— The search is done once the endpoint refinement step has been 
completed for each interval over which the state is true. 
¢ For numeric searches, once the monotone windows have 
been found, the result window still must be computed: 


— Local and absolute extrema can be found without further 
searching. 


— Equalities, inequalities, and adjusted absolute extrema require 
a second search pass in which each monotone interval is 
examined. 


» These searches don’t require sequential stepping and are 
usually relatively fast compared to the interval bracketing search. 


¢ Since the roots are found by a search process, they are 
subject to approximation errors. 


— NOTE: The geometric condition may not be satisfied at or near the 
endpoints of the result window’s intervals. 


¢ Usually data errors are large enough so that the accuracy of 
the result is poorer than its precision. 
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Geometry Finder Subsystem 
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Specifying Workspace Dimensions 
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¢ GF numeric scalar searches can require relatively 
large amounts of memory to store intermediate 
results. 


— For Fortran Toolkits, user applications must declare a buffer of 
workspace windows. 


— For C, IDL, and MATLAB Toolkits, users need only specify the 
maximum number of workspace window intervals that are needed; 
these Toolkits will dynamically allocate the amount of memory 
required by the specified workspace window interval count. 

¢ In most cases, users need not accurately compute the 
required amount of workspace; it’s usually safe to 
specify a number much larger than the amount 
actually needed. 


— For example, if the result window is anticipated to contain 100 
intervals, specifying a workspace window interval count of 10000 will 
very likely succeed. 


— See the GF Required Reading and the API documentation for details. 
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API Example: GFDIST 


Solve for Distance Constraints 


Geometry Finder Subsystem 
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API Example: GFDIST 


Navigation and Ancillary Information Facility 


¢ GFDIST finds times when a specified constraint on the 
distance between two ephemeris objects is met. 
— The distance is the norm of a position vector 


— The position vector is defined using a subset of the inputs accepted 
by SPKPOS: 


» Target 
» Observer 
» Aberration Correction 
— The constraint is a numeric relation: equality or inequality relative to 
a reference value, or attainment of a local or absolute extremum. 
¢ The search is conducted within a specified 
confinement window. 


¢ The search produces a result window which indicates 
the time period, within the confinement window, over 
which the constraint is met. 
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Language Differences 
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¢ Due to use of SPICE windows, some of the GFDIST 
set-up code differs substantially across languages. 
— We’ll show how to perform the set-up unique to each language. 


» Note: there’s no set-up to do in the MATLAB case; hence there’s 
no MATLAB-specific set-up slide. 


— The rest of the code is sufficiently parallel across languages to 
justify showing only the Fortran code. 


— Note however that the treatment of workspace differs across 
languages: only in Fortran does the user application have to pass 
the workspace array to the GF API routine. 
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Fortran Set-up 
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Fortran constant and variable declarations 


‘Declare confinement window, result window, and workspace array 


INCLUDE ‘gf.ine’ include GF parameters 
such as NWDIST 


INTEGER LBCELL 


PARAMETER ( LBCELL = -5 ) Choose a “large” value for window size (called “MAXWIN” 
INTEGER MAXWIN here), if you’re not sure what size is required. The actual 

requirement depends on underlying geometry, confinement 
PARAMETER ( MAXWIN = 200000 ) window, and search step size. 


DOUBLE PRECISION CNFINE (LBCELL : MAXWIN ) 
DOUBLE PRECISION RESULT (LBCELL : MAXWIN ) 
DOUBLE PRECISION WORK (LBCELL : MAXWIN, NWDIST ) 


Initialization...typically done once per program execution 


eee confinement and result windows. Workspace need not be initialized 
ere. 


CALL SSIZED ( MAXWIN, CNFINE ) 
CALL SSIZED ( MAXWIN, RESULT ) 
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C Set-up 


Navigation and Ancillary Information Facility 


C constant and variable declarations 


Declare confinement and result windows, as well as size of workspace. 
Include CSPICE macro, typedef, 
#include “SpiceUsr.h” ¢ and prototype declarations 


Choose a “large” value for window size (called “MAXWIN” 
here), if you’re not sure what size is required. Actual 


: requirement depends on underlying geometry, confinement 
#define NINTVL 100000 | window, and search step size. The window size must be twice 
#define MAXWIN (2 * NINTVL ) the maximum number of intervals the window is meant to hold. 


SPICEDOUBLE_CELL (cnfine, MAXWIN ); These macro calls declare CSPICE 
SPICEDOUBLE_CELL (result, MAXWIN ); Window stuelures ane ser mer 


maximum sizes. 
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IDL Set-up 


Navigation and Ancillary Information Facility 


IDL window creation 


; ; Choose a “large” value for window size (called 
Icy windows are created dynamically: “MAXWIN” here), if you’re not sure what size is 
, - ‘ required. Actual requirement depends on underlying 
cnfine cspice_celld ( MAXWIN ) geometry, confinement window, and search step size. 
The window size must be twice the maximum number 
of intervals the window is meant to hold. 


The output result window is created by CSPICE_GFDIST;; it 
does not require a constructor call by the user application. 
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All Languages: Additional Set-up 


Navigation and Ancillary Information Facility 


Initialization...typically done once per program execution 


Tell your program which SPICE files to use (“loading” files) 
CALL FURNSH (‘spk file name’) } Better yet, replace these two calls with a 


single call to a “meta-kernel” containing 
CALL FU RNSH (leapseconds_file_name’) the names of all kernel files to load. 


The next step is to insert times into the confinement window. The 
simplest confinement window consists of a single time interval. 


Convert UTC start and stop times to ephemeris time (TDB), if needed: 
CALL STR2ET ('‘utc_start', tdb_0) 
CALL STR2ET (‘utc_stop’, tdb_1) 


Insert start and stop times into the confinement window: 
CALL WNINSD ( tdb_0, tdb_1, CNFINE ) 
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Execute the Search -1 


Navigation and Ancillary Information Facility 
Search execution...done as many times as necessary during program execution 
Choose: 
— Geometric input arguments: 
» Target 
» Observer 
» Aberration correction 
— Constraint arguments: 
» Relation 
» Reference value, if applicable 
» Adjustment value, if applicable 
— Search step size 


Then call GFDIST: 
CALL GFDIST (target, Scien. Seid MAE ‘relate’, 


inputs Input/output output 
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Execute the Search -2 


Navigation and Ancillary Information Facility 
Search execution, continued 


Extract intervals from the result window: 
DO | = 1, WNCARD( RESULT ) 


[Fetch the endpoints of the Ith interval of the result window.] 
CALL WNFETD( RESULT, I, START, FINISH ) 
[ use START, FINISH... ] 
END DO 


¢ Note: 
— The result window may be empty. 
— The constraint might not be satisfied at or near the endpoints of any interval of RESULT. 


» Consider using the window contraction routine WNCOND to shrink the intervals of 
the result window slightly, so the constraint is met on the entire result window. 


» Caution: DON’T use WNCOND for minimum, maximum, or equality searches---the 
result window will disappear! (WNCOND is ok for adjusted absolute extrema search 
results, though, since the result intervals are not singletons.) 

» Caution: using WNCOND may not be desirable if the window is an intermediate 
result: subsequent, derived results might be made less accurate. 
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INPUTS 


Arguments of GFDIST - 1 


Navigation and Ancillary Information Facility 


TARGET* and OBSERVER”: Character names or NAIF IDs for the 
end point and origin of the position vector (Cartesian position and 
velocity vectors) whose length is the subject of the search. Below, 
we'll simply call this length “the distance.” 

— The position vector points from observer to target. 


CORRECTION: Specification of what kind of aberration 
correction(s), if any, to apply in computing the distance. 


— Use ‘LT+S’ to use the apparent position of the target as seen by the 
observer. ‘LT+S’ invokes light time and stellar aberration corrections. 


— Use ‘NONE’ to use the uncorrected (aka “geometric”) position, as 
given by the source SPK file or files. 


See the headers of the subroutines GFDIST and SPKEZR, the document 
SPK Required Reading, or the “Fundamental Concepts” tutorial for details. 
See the SPK tutorial backup charts for examples of aberration correction 
magnitudes. 


* Character names work for the target and observer inputs only if built into SPICE or if registered using the 
SPICE ID-body name mapping facility. Otherwise use the SPICE numeric ID in quotes, as a character string. 
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Arguments of GFDIST - 2 


Navigation and Ancillary Information Facility 


INPUTS 


¢ RELATE, REFVAL, ADJUST: parameters specifying a constraint to be met 
by the distance. 
— RELATE may be any of ‘=", ‘>’, ‘<‘, ‘LOCMAX’, ‘LOCMIN’, ‘ABSMAX’, ‘ABSMIN’ 


— If RELATE is an equality or inequality operator, REFVAL is the corresponding 
double precision reference value. Units are km. 


» For example, if the constraint is “distance = 4.D5 km,” then RELATE is ‘=‘ 
and REFVAL is 4.D5. 


— If RELATE specifies an absolute maximum or minimum, ADJUST is the 
adjustment value. Units are km. 


» Set ADJUST to 0.D0 for a simple absolute maximum or minimum. 


» Set ADJUST to a positive value ADJ for either DISTANCE > absolute max - 
ADJ or DISTANCE < absolute min + ADJ. 


¢ STEP: search step size, expressed as TDB seconds. 


¢ CNFINE: the confinement window over which the search will be performed. 


¢ MW, NW, WORK: the maximum capacity of each workspace window, the 
number of workspace windows, and the workspace array. 


OUTPUTS 


¢ RESULT: the window of times over which the distance constraint is 
satisfied. 
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